… + solver_mode error contract

Per proteus-tests.md §1 every new test needs an edge case, an error-contract
path, and non-trivial discrimination guards. The previous single-scenario
happy-path test had only the discrimination guards. Two additions bring it
to §1 compliance.

(1) Parametrize the coupled test over three IC scenarios that sweep the fO2
+ H budget axes through the atmodeller chemistry:

  - earth_like_IWp2: IW+2, 3000 ppmw H. Nominal Earth anchor; mildly
    oxidised, water-dominated outgassing.
  - reducing_IWm2: IW-2, 3000 ppmw H. H2 dominates over H2O above this
    buffer offset; exercises the reducing branch of the equilibrium
    network.
  - oxidising_IWp4_high_H: IW+4, 10000 ppmw H. Strongly oxidised, high
    volatile budget; exercises the upper-oxidation branch and a higher
    P_surf regime than the nominal anchor.

The fO2 sweep takes atmodeller's chemistry through the H2/H2O dominance
flip (near IW-2 in PROTEUS' default species list) and into the high-P_surf
regime at IW+4 + high H budget. A regression that breaks one branch
silently passes the previous single-scenario test; a 3-scenario span
catches it.

(2) Add a dedicated error-contract test for the atmodeller solver_mode
schema validator. The contract from src/proteus/config/_outgas.py:108-111
says solver_mode must be in {'robust', 'basic'}. The new test:

  - asserts solver_mode='unknown' raises ValueError with the field name
    in the message;
  - asserts the known-good values 'robust' and 'basic' round-trip, so a
    regression that broke the validator into raising on every input is
    not masked;
  - asserts the default value is inside the enum, catching a stale-default
    regression that would otherwise only surface at runtime.

Local wall time: 4 tests, 31.75 s total (vs ~14 s baseline). Well under
the 300 s integration-tier ceiling.

Per proteus-tests.md §1 every new test needs an edge case, an error-contract
path, and non-trivial discrimination guards. The single-scenario xcheck had
the factor-of-3 cross-backend ratio guard (rigorous against the CALLIOPE
docs' Fischer-default expectation) but was missing the §1.1 edge-case and
§1.2 error-contract clauses.

(1) Parametrize the cross-backend test over three fO2 scenarios at the same
H budget:

  - earth_IWp2: nominal Earth anchor, IW+2.
  - reducing_IWm2: IW-2, H2-dominated chemistry branch.
  - oxidising_IWp4: IW+4, upper-oxidation branch.

The fO2 axis is the primary driver of the documented divergence between
CALLIOPE (Fischer 2011) and atmodeller (Hirschmann composite); holding the
factor-of-3 P_surf ratio bound across [IW-2, IW+4] checks that the
agreement is robust to the redox dimension, not just to the IW+2
fiducial.

(2) Add a dedicated error-contract test for the outgas module schema
validator. The contract from src/proteus/config/_outgas.py:158-160 says
Outgas.module must be in {'calliope', 'atmodeller', 'dummy'}. The new test:

  - asserts module='unknown' raises ValueError with the field name in
    the message;
  - asserts the three documented values round-trip without raising;
  - asserts the default is inside the enum, catching a stale-default
    regression that would only otherwise surface at fixture-construction
    time.

Local wall time: 4 tests, 41 s total (vs ~18 s baseline). Well under the
300 s integration-tier ceiling.

…rror contract

Per proteus-tests.md §1 every new test needs an edge case, an error-contract
path, and non-trivial discrimination guards. The previous single-scenario
test had only the discrimination guards. Two additions bring it to §1
compliance.

(1) Parametrize the coupled test over three IC scenarios:

  - earth_IWp2: 1 M_Earth, IW+2, 3000 ppmw H. Nominal Earth anchor.
  - reducing_IWm2: IW-2, 3000 ppmw H. H2/CH4-dominated chemistry branch.
  - oxidising_IWp4_high_H: IW+4, 10000 ppmw H. Higher-pressure oxidised
    branch.

The fO2 axis stresses the calliope chemistry network's reducing vs
oxidising branches; the aragog entropy solver sees the same dummy
structure in each but couples through the partial-pressure spectrum and
the dissolved-mass profile that calliope computes.

(2) Add a dedicated error-contract test for the interior_energetics module
schema validator. The contract from src/proteus/config/_interior.py says
Interior.module must be in {'spider', 'aragog', 'dummy', 'boundary'}.
The new test:

  - asserts module='unknown' raises ValueError with the field name in
    the message;
  - asserts the four documented values round-trip without raising;
  - asserts the default is inside the enum, catching a stale-default
    regression that would otherwise only surface at fixture-construction
    time.

Local wall time: 4 tests, 8 min 54 s total (vs ~180 s baseline). Each
parametrized aragog scenario is ~175 s on local Mac Studio; on macOS GHA
expect ~280 s per scenario, well under the 600 s per-test timeout.

…ntract

Last of the five Wave 1 + Wave 2-B tests being raised to proteus-tests.md
§1 compliance. Same template as the aragog+calliope hardening, swapped
for the atmodeller outgas backend.

(1) Parametrize the coupled test over three IC scenarios that sweep the
fO2 + H budget axes through the atmodeller chemistry:

  - earth_IWp2: 1 M_Earth, IW+2, 3000 ppmw H. Nominal Earth anchor.
  - reducing_IWm2: IW-2, 3000 ppmw H. Reducing branch of the atmodeller
    equilibrium network.
  - oxidising_IWp4_high_H: IW+4, 10000 ppmw H. Higher-pressure oxidised
    branch.

The aragog entropy solver sees the same dummy structure in each case;
the parametrize span surfaces bugs in the partial-pressure / dissolved-
mass round-trip between atmodeller's JAX solver and the PROTEUS helpfile
schema that the previous single-scenario test could not catch.

(2) Add a dedicated error-contract test for the atmodeller
solver_multistart schema validator. The contract from
src/proteus/config/_outgas.py:113 says solver_multistart must be > 0.
The new test:

  - asserts solver_multistart=0 raises ValueError;
  - asserts solver_multistart=-1 also raises;
  - asserts known-good positive values (1, 10) round-trip without
    raising;
  - asserts the default is positive, catching a stale-default
    regression that would otherwise only surface when atmodeller's
    wrapper tried to index multistart-1.

Local wall time: 4 tests, 9 min 15 s total (vs ~192 s baseline). Each
parametrized aragog+atmodeller scenario is ~150-220 s on local Mac Studio;
on macOS GHA expect ~280-380 s per scenario, under the 600 s timeout.

With this commit the rigor pass on all five Wave 1 + Wave 2-B pair tests
is complete:

  - test_integration_mors_zephyrus.py: 13 s, 4 tests
  - test_integration_atmodeller_dummy.py: 32 s, 4 tests
  - test_integration_outgas_xcheck.py: 41 s, 4 tests
  - test_integration_aragog_calliope.py: 8 min 54 s, 4 tests
  - test_integration_aragog_atmodeller.py: 9 min 15 s, 4 tests

Total integration-tier wall time on local Mac Studio: ~20 min.
Nightly Linux estimate: ~25-30 min. Nightly macOS estimate: ~30-35 min.
Both still inside the 60 min soft target and 90 min hard cap.

ruff format collapses the multi-line _AragogAtmodellerScenario(...) call
that previously spanned multiple lines into a single line where it fits
within 96 chars. The CI ruff format check caught the difference; local
ruff check alone passed because the rule is format-only, not lint.

…or edge case

The earlier rigor pass parametrized aragog+calliope and aragog+atmodeller
over three fO2 scenarios. Empirically a single 2-timestep aragog test
takes ~180 s on local Mac Studio, ~315 s on macOS GHA, but ~750 s on
Linux GHA because JAX CPU-only is ~2.5x slower on x86 than on the
M-series ARM that macOS GHA uses for the option-Z CVode + JAX path.
Three parametrized scenarios per aragog file would push nightly Linux
wall time toward ~75 min just for aragog, busting the 60 min soft target.

Decision: keep aragog tests single-scenario, rely on the schema-validator
error-contract sibling tests for the §1 edge-case requirement. The fO2
axis is already covered by atmodeller_dummy and outgas_xcheck (which run
quickly because they don't pay the aragog wall-time cost), so the aragog
parametrize was duplicating cross-backend coverage without testing a
distinct aragog-side branch. The aragog entropy solver sees the same
dummy structure across all three fO2 scenarios; the only thing that
varies is the partial-pressure spectrum, which the outgas-side tests
already pin.

Both aragog test files now contain:
  - A single Earth-IC fiducial integration test (1 M_Earth, IW+2,
    3000 ppmw H budget) with the same conservation + stability invariants
    as before.
  - An error-contract sibling test exercising the schema validator
    boundary inputs (interior_energetics module enum for aragog+calliope,
    atmodeller solver_multistart > 0 guard for aragog+atmodeller).

The module-level pytest timeout is raised from 600 s to 1200 s to give
~2x headroom on the slowest runner (Linux GHA). Wall-time budget per
file goes from ~9-15 min parametrized to ~3-6 min single-scenario.

Local timing on Mac Studio: 4 tests across both files, 6 min 10 s total
(2 aragog runs of ~3 min each + 2 fast error-contract tests).

The diffrax solver path in src/proteus/interior_energetics/aragog_jax.py
is currently gated on a hardcoded _DIFFRAX_RESEARCH_ONLY = False
constant in aragog.py and not exposed in the TOML schema. The dispatcher
code around it (config plumbing, output translation, error handling) is
production code that would run if the gate ever flipped, but had zero
test coverage before this commit.

Four mocked unit tests cover the dispatcher contract without invoking
the broken diffrax solver (kvaerno3 stalls on the first crystallization
step in CHILI Earth runs; implicit_euler exhausts diffrax's
optx.Newton on a non-stiff pure-liquid step).

  - test_build_jax_components_raises_when_spider_eos_dir_missing:
    exercises the error contract on the spider EOS directory guard
    with two boundary inputs (None, nonexistent path). Catches a
    regression that would let the JAX backend silently fall back to
    an empty EOS instead of hard-failing with FileNotFoundError.

  - test_run_solver_raises_when_diffrax_result_fails: mocks
    solve_entropy to return success=False, asserts RuntimeError fires
    with the documented diagnostics in its message AND that
    interior_o._last_entropy is NOT written despite the failure (side-
    effect-not-run discrimination: a regression that moved the
    _last_entropy assignment above the success check would silently
    corrupt the next coupling step).

  - test_extract_output_mass_closure: feeds a synthetic SolveEntropyResult
    plus mesh + EOS into _extract_output and pins the conservation
    invariant M_mantle_liquid + M_mantle_solid == M_mantle to within
    rel=1e-12. Uses an asymmetric phi profile so a regression that
    swapped liquid/solid bookkeeping (computing the solid formula for
    M_mantle_liquid) is caught: the test re-runs with a skewed
    profile (mean phi=0.2) and asserts liquid/total == 0.2, which
    would land at 0.8 with the swapped formula.

  - test_run_solver_includes_heating_when_radiogenic_enabled:
    captures the heating array passed to solve_entropy and asserts
    it matches the radionuclide get_heating() return at t_start.
    Catches a regression that silently dropped the radiogenic
    contribution.

All tests mock aragog.jax components (solve_entropy via
aragog.jax.solver, evaluate_phase via aragog.jax.phase). The local
import of solve_entropy inside run_solver means the patch target is
'aragog.jax.solver.solve_entropy', not the proteus-side wrapper module.
Same for evaluate_phase.

Wall time: 4 tests, 1.4 s total. Unit tier.

The two real-aragog integration tests time out on Linux GHA (1200 s
ceiling) while passing in ~440 s on macOS GHA and ~180 s on local
Mac Studio. Other integration tests on the same Linux runner finish in
5 to 32 s, so the slowdown is aragog-specific, not generic Linux GHA
slowness.

Aragog defaults to backend='jax' (option Z: scipy-CVode with a
JAX-derived RHS and analytic Jacobian via jax.jacrev). The numpy
backend (scipy-CVode with the numpy RHS) is a validated production
path already used by input/chili/nightly_np_dilOn_utblOn.toml and
input/chili/stage_4_4_a2_wet_1me_atmod.toml.

Pin backend='numpy' on test_aragog_calliope_two_timesteps and
test_aragog_atmodeller_two_timesteps so they stop tripping the 1200 s
ceiling and produce a discriminator value for the Linux JAX-CPU
hypothesis. If the numpy backend lands at similar wall time as
macOS-with-jax (~315 s), option-Z on Linux x86 is confirmed as the
bottleneck. If numpy is also slow on Linux, the bottleneck is in
CVode or the stiffness profile and we look elsewhere.

Add a one-shot environment log and per-attempt solve() timing in
aragog.py, gated on PROTEUS_CI_NIGHTLY=1 so production runs are not
affected. The env log records platform.machine(), CPU count, JAX
backend, devices, version, JAX_PLATFORMS, XLA_FLAGS, aragog backend
and tolerances. The per-attempt timing records wall time and CVode
status for every solver.solve() call.

Local Mac Studio with backend='numpy' runs the calliope test in 390 s
(vs 180 s with the jax backend). The numpy backend is slower locally
but should be more resilient on Linux x86 where the JAX-CPU compile
and Jacobian path are known to be slow. The nightly will confirm.

375 interior_energetics unit tests pass locally with the diagnostic
changes in place.

Linux GHA needs > 1200 s for a single aragog setup + first solver step
even with backend='numpy' (the bisect from the previous commit). The
360 s setup phase on Linux x86 (EOS table load + EntropySolver
construction inside the aragog library) alone exceeds the full macOS
GHA wall time of ~440 s for the same test. Both backends hit the
1200 s pytest timeout on Linux, so the bottleneck is in the aragog
setup itself, not in the JAX option-Z path.

Move test_aragog_calliope_two_timesteps and
test_aragog_atmodeller_two_timesteps to two new slow-tier files
(test_slow_aragog_calliope.py and test_slow_aragog_atmodeller.py)
with timeout(2400) and add them to the nightly slow-tier file list
in ci-nightly.yml. The slow-tier 75 min step cap easily fits two
2400 s tests with margin.

Restore the production default backend='jax' on both moved tests so
the tests exercise the actual production solver path again, not the
numpy fallback. The numpy bisect was a temporary discriminator; the
production tests are the contract.

Leave the sub-second error-contract validator tests in the existing
test_integration_aragog_calliope.py and test_integration_aragog_atmodeller.py
files at the integration tier (these are config-only and run in <1 s).
Each file now contains only its respective validator test.

PR-CI integration step on Linux drops from 45 min back to the ~5 min
baseline. Nightly slow step gains two aragog tests at ~440 s each on
macOS and ~1800-2200 s each on Linux (projected; the second solve
step is fast once setup is amortised).

Diagnostic logging in src/proteus/interior_energetics/aragog.py from
the previous commit stays in place (gated on PROTEUS_CI_NIGHTLY=1) so
future nightly runs continue to record per-attempt solver timing and
first-call setup breakdown. Useful safety net for upstream aragog
perf regressions.

The two slow aragog tests claim to exercise the production solver path
(scipy-CVode with a JAX-derived RHS and analytic Jacobian) but only
assert physics invariants on the output. If the JAX import or pytree
construction silently fails inside the wrapper, the solver falls back
to its finite-difference Jacobian and the test still passes for the
wrong reason.

Two changes close the gap:

1. The wrapper now sets _jax_factory_call_count on the aragog solver
   and increments it from inside the factory closure. Both slow tests
   read the counter after the run and assert it is >= 1, so the
   analytic-Jacobian factory must have been consumed at least once
   for the test to pass.

2. Under PROTEUS_CI_NIGHTLY=1 the three fallback paths in
   _maybe_install_jax_cvode_factory (solver is None, JAX ImportError,
   and the broad pytree-construction Exception) escalate to
   RuntimeError instead of logging a warning and returning. Nightly
   runs cannot silently slip onto the FD path; PR-CI and local runs
   keep the warn-and-fallback behavior.

Tested locally on the Mac Studio: test_aragog_calliope_two_timesteps
passes in 178 s with the new guard, test_aragog_atmodeller_two_timesteps
in 187 s.

The PyPI dist of fwl-aragog (26.5.13) does not declare
scikits-odes-sundials as a runtime dep, so the CI environment installs
fwl-aragog without it. Aragog's EntropySolver then silently falls back
from CVODE to scipy Radau, and the JAX analytic-Jacobian factory the
PROTEUS aragog wrapper installs on the solver is never invoked.

The slow-tier aragog tests on macOS surfaced this with the new
factory-call-count assertion (call_count=0) on nightly 26015937351.

Two changes to setup-proteus:

1. System package: libsundials-dev (apt, Ubuntu 24.04 -> SUNDIALS 6.4.1)
   and sundials (brew, macOS -> 7.x). Both versions satisfy
   scikits-odes-sundials 3.1.x.

2. Explicit pip install of scikits-odes-sundials>=3.0.0 right after the
   PROTEUS install, with SUNDIALS_INST set on macOS so the build finds
   the brew install. Includes an import-check that fails the step if
   scikits.odes did not actually import.

Brew-downloads cache key already hashes action.yml, so the new
sundials package gets picked up on the next run automatically.

Pip cannot install scikits-odes-sundials on the GitHub runners
without significant work: Ubuntu 24.04's apt ships SUNDIALS 6.4,
scikits-odes-sundials 3.1.x needs SUNDIALS 7.0+; brew's sundials
is MPI-coupled by default and fails to compile against the
Cython extensions without open-mpi present.

Conda-forge owns both SUNDIALS 7.x and the matched scikits.odes
binaries on Linux and macOS, so route the production CVODE
dependency through it. Replace the setup-python action with
conda-incubator/setup-miniconda using the miniforge-latest
distribution, create a 'proteus' env with python 3.12, and
mamba-install sundials + scikits.odes from conda-forge before
pip-installing the rest of PROTEUS into the same env.

Shell defaults across ci-pr-checks, ci-nightly, and ci-warmup
move to `bash -el {0}` so the conda env activates for every
step that uses python.

Drop the now-redundant apt libsundials-dev and the separate
pip install scikits-odes-sundials step.

The aragog slow-tier tests added in the previous commit will
now exercise the production CVODE + JAX analytic-Jacobian path
on CI; the factory-call-count assertion would otherwise have
caught a silent fallback to scipy Radau.

The production CVODE+JAX path runs noticeably slower on Linux x86
than on macOS arm64; a single solve() step takes ~30 min on Linux
vs ~3 min on macOS. The previous timeout(2400) on the two slow
aragog tests fired on Linux GHA last nightly, then the 75 min
slow-tier step cap killed the second test before it could finish.

Bump the per-test timeout from 2400 s to 3600 s on both
test_slow_aragog_calliope.py and test_slow_aragog_atmodeller.py,
and lift the slow-tier step cap from 75 min to 120 min on both
Linux and macOS jobs. The surrounding job cap of 180 min still
covers cold-cache setup (~15 min) and the unit/smoke/integration
tiers.

The CVODE+JAX path itself is correct: macOS nightly 26019373854
ran both tests to completion in 272 s and 334 s with the new
factory-call-count assertion passing. The Linux delta needs a
separate diagnostic pass.

juliacall 0.9.33 changed how it computes the PythonCall.jl
development path; on conda env layouts it now passes
`<env>/lib/python3.12` to Pkg.develop, which has no Project.toml
there, so the post-install Julia env resolution fails with
"could not find project file (Project.toml or JuliaProject.toml)
in package at /home/runner/miniconda3/envs/proteus/lib/python3.12".

0.9.32 falls back to Pkg.add(name="PythonCall") on this same
layout and works. Pin under 0.9.33 until the upstream issue is
resolved.

Nightly 26031660803 hit this on both Linux and macOS at the
"Set up PROTEUS environment" step; the previous nightly on the
same conda setup (commit f9747a3) installed juliacall 0.9.32
and worked.

The aragog wrapper logs per-solve wall times under PROTEUS_CI_NIGHTLY=1
but pytest captures the log on passing tests, so the workflow log only
ever showed those lines on failure. Add --log-cli-level=INFO + a custom
format to both Linux and macOS slow-tier pytest calls so the diag lines
stream live regardless of pass/fail.

Add a parallel Linux log upload step matching the macOS one
(nightly-linux-logs artifact containing junit XML + tee'd pytest output)
so the raw stdout is preserved across nightly runs for offline analysis.

This unblocks localising the 12-14x macOS-vs-Linux slowdown on the
production CVODE+JAX path: with the artifact + live INFO logs we can
read per-solve wall times directly on the next nightly without modifying
the test code.

The existing diag log reports setup and jax_cvode_factory as single
wall-time numbers each. Last nightly localised the 12-14x Linux delta
to those two phases (47x and 48x slower than macOS) but didn't say
which line inside them dominates. Add per-call timers around:

- EntropyEOS(...) and EntropySolver(...) inside setup_solver(): tells
  us whether the 379s on Linux is PALEOS table load (scipy interp
  construction) or aragog's solver constructor (mesh build,
  phase-boundary tables).

- EntropyEOS_JAX(...) and MeshArrays.from_numpy_mesh(...)+PhaseParams
  inside _maybe_install_jax_cvode_factory(): tells us whether the 301s
  on Linux is the JAX EOS trace+compile or the pytree construction.

All gated on PROTEUS_CI_NIGHTLY=1; production wall time unchanged.

Break the single, sprawling Usage page into an overview plus three topic
pages: running and output, parameter grids, and postprocessing and chemistry.
Move the melting-curve exporter documentation to the Reference section next to
the interior configuration.

Remove the Version-checking and Installation-management sections, which
duplicated the diagnose-and-update and installation pages. The install-all and
update-all commands are now documented on those pages instead. Update the
navigation and the cross-links between pages.

Relocate the CHILI intercomparison base configuration (_base.toml and
_base.grid.toml) and its generator target from input/chili/ to
input/tutorials/chili_intercomp/, so all CHILI input lives under
input/tutorials/. Repoint tools/chili_generate.py, the base grid's ref_config,
the generated-config gitignore rules, and the docstring references in the
config schema and tests.

The Solar System CHILI tutorial is unaffected: it uses
input/tutorials/tutorial_earth.toml, tutorial_venus.toml, and chili_grid/,
none of which change.

Take the CHILI intercomparison generator (chili_generate.py), the submission
post-processor (chili_postproc.py) with its test, and the multi-planet base
configuration out of the PROTEUS tree; they belong with the paper analysis
code rather than the model source.

PROTEUS keeps the Solar System CHILI tutorial and everything that reproduces
its published figures: input/tutorials/chili_grid/, tutorial_earth.toml,
tutorial_venus.toml, and tools/plot_chili_comparison.py. Also drop the
now-unused input/chili gitignore patterns.

No code writes chili.csv; the entry is left over from earlier tooling that
has since been removed.

Replace the inline, never-run example with a committed grid config at
input/tutorials/tutorial_grid.toml. It sweeps three axes with three methods
(explicit planet mass, log-spaced orbital distance, linearly spaced hydrogen
budget) over the fast all-dummy base, giving 27 cases that each stop at
solidification or energy balance.

The page now matches that config exactly, documents the required top-level
keys (a missing one crashes the run), explains the two stop conditions, and
shows with two figures what each axis controls: orbital distance sets whether
the planet solidifies or stays molten, planet mass sets the cooling time, and
the hydrogen budget sets the surface pressure. A caveats section flags that the
dummy physics is illustrative, not predictive.

Add a tip callout at the top of the parameter grids how-to pointing to the
worked parameter grid sweep tutorial, alongside the existing inline and
see-also links.

Document the planet thermal initial conditions and how configuration
defaults work.

Add a Usage page on initial thermal conditions that explains what the
starting mantle state controls, walks through the temperature_mode
options, and recommends the core-mantle-boundary anchored start
(adiabatic_from_cmb by default, or liquidus_super with a superliquidus
offset for an EOS-agnostic fully molten mantle).

Expand the configuration guide with a section on defaults: every
parameter has a built-in default in the schema, where to find each
default, and how to read the fully resolved configuration for a run
from init_coupler.toml.

Switch the default planet.temperature_mode to 'liquidus_super', which
anchors the initial mantle adiabat at the silicate liquidus plus a
superliquidus offset (delta_T_super) at the core-mantle boundary. This
gives an EOS-agnostic, fully molten initial state across Earth-mass and
super-Earth mantles, and is the recommended starting condition.

The all-dummy quick-start config (input/dummy.toml) is pinned to
'adiabatic_from_cmb' so it keeps running without the silicate liquidus
lookup and therefore without any external structure solver.

Update all_options.toml to the new default, refresh the planet
configuration reference and the initial-conditions guide to present
liquidus_super as the default, and pin the schema default in the tests.

Make the liquidus_super initial condition robust now that it is the
default, and correct its literature citation.

Fix the citation: the MgSiO3 liquidus is Fei et al. (2021), Nat. Commun.
12, 876, not the unrelated PRL 127, 135701. Correct it in the schema
docstring and the interior comment, and label the curve MgSiO3 (not
peridotite) in the docs.

Keep the all-dummy path free of the silicate liquidus lookup. The dummy
interior structure now raises a clear error when Zalmoxis is missing
instead of an opaque import failure, and points to adiabatic_from_cmb.
Pin the all-dummy test fixtures to adiabatic_from_cmb so they stay
solver-free and initial-condition-stable, and add a test that the dummy
quick-start config keeps that pin.

Guard the super-Earth regime. Warn when the core-mantle-boundary
pressure exceeds the entropy-table maximum (the inversion clamps P
silently) or the Fei liquidus calibration near 500 GPa (where the anchor
extrapolates). Clamp the dummy adiabat to the local liquidus when the
linearized integration dips below it, so the initial profile stays
molten. Describe delta_T_super as a heuristic margin, not a guarantee.

Point the SOCRATES row in the module versions table at its documentation
site (proteus-framework.org/SOCRATES) instead of the source repository,
matching the AGNI and SPIDER rows. Also render optional modules with no
pinned version as "n/a" for a consistent placeholder.

Bring in the schematic SVG fix and the funder-logo dark-mode update from
main. Resolve the two overlaps by keeping the new light/dark logo grid
while preserving this branch's additions: the Cambridge funder entry
(reformatted into the light/dark layout) and the figure-caption styling
in extra.css.

Restructure the README to match the sibling-module style while staying
concise. Add a short features list and a get-started section with the
all-dummy quick-start command, lead with a one-line summary, and keep the
full project description and pronunciation. The status badges now mirror
the documentation landing page exactly, and the dark-mode logo matches
the docs.

Correct several documented defaults and add fields that were missing
from the configuration reference, so the tables match the schema:

- Interior: Boundary rtol/atol are 1e-6/1e-9, write_flux_diagnostics
  defaults to false. Add core_bc, surface_bc_mode, tolerance_struct,
  log_output, scalar_gravity_override, phi_step_cap, and the Zalmoxis
  update_dw_comp_abs / update_stale_ceiling / dry_mantle knobs.
- Time-stepping: add the maximum_rel row.
- Escape and outgassing: add boreas to the escape module choices,
  document the escape.boreas block, and add the CALLIOPE nguess/nsolve
  solver fields.
- Atmosphere: add the AGNI fdo, check_safe_gas, spectral_file, and
  grey_opacity_lw/sw fields.
- Planet: add R_int_override and note that from_mantle_redox is reserved.

Also clarify in the coupling-loop page that the energy-residual columns
are written on every run, while write_flux_diagnostics only controls the
optional per-component Aragog output, and fix the evap_efficiency
docstring type from bool to float.

Several runnable snippets did not work when copied verbatim:

- Grid guide: the worked grid TOML omitted the required symlink,
  max_days, and max_mem keys, so a verbatim copy raised KeyError before
  the grid started. Add them and correct the stated Slurm defaults to
  12 GB and 1 day.
- Running guide: all_options.toml sets out.path = "auto", so results
  land in a timestamped run_<timestamp>_xxxx folder, not output/all_options/.
  Reword the path references and point the nohup log at output/.
- Inference guide: use planet.elements.H_budget (not H_ppmw), and the
  valid kernel and acquisition-function names (MAT3/2, plus E-LogEI).
- Kapteyn guide: join the wget/bash commands that were wrapped onto a
  separate line, and render the Condor submit file without the stray
  indentation that broke copy-paste.
- Habrok guide: spell out proteus start --offline -c instead of the
  fragile -oc flag bundling.
- Parameter-grid tutorial: fix the cluster-guide links to point at
  ../How-to/, and correct phi_crit to 0.01.

- Output reference: the status-code table was shifted by one from code
  11 onward. Mark 11 as unused and realign maximum-iterations, target-time,
  and net-flux-small to codes 12, 13, 14.
- Binodal validation: point the entry at the test that actually exists
  (the H2 molar-mass pin) and cite the published Rogers, Young &
  Schlichting (2025) MNRAS paper instead of a placeholder preprint id.
- Star wrapper validation: correct the exponent-guard values (cube root
  ~1613 K, fifth root ~84 K) in both the page and the test comment.
- Add a validation page for the liquidus-super interior-structure IC,
  which pins the Fei et al. (2021) liquidus anchor, with a nav entry.

- Model overview: list BOREAS among the escape implementations.
- Test-framework page: the 300 K black-body flux is 459.30 W/m^2.
- Documentation guide: the Tutorials folder is no longer empty.
- Initial-conditions guide: use the White & Li (2025) citation style.
- Contributing guide: restore the dropped word in the ruff instruction,
  fix the grammar, and point the link at the code-style workflow file.
- JOSS paper: use the case-correct documentation URL.

The editable setup scripts for Aragog and Zalmoxis continued past a
failed clone and ran the editable install in the wrong directory. Add
explicit failure checks on the clone, directory change, and install so
the script stops with a clear error instead of installing the wrong
package.

Clarify that the zalmoxis structure module always interprets core_frac
as a mass fraction and ignores core_frac_mode; emit a warning when a
radius fraction is requested with that module so the behaviour is not
surprising.

Allow params.dt.maximum_rel = 0.0 to disable the time-proportional step
allowance, which the documentation already describes; the validator
previously rejected it.

Two problems in how the deprecated num_tolerance and spider.tolerance_rel
aliases resolve to interior_energetics.rtol:

- An explicit rtol set to the default value (1e-10) was treated as unset,
  so a deprecated alias would silently override it. rtol and num_tolerance
  now default to a sentinel, so an explicitly-supplied value is always
  honoured; a conflicting alias raises instead of silently winning.
- spider.tolerance_rel emitted a deprecation warning even when it matched
  the explicitly-set rtol, contradicting the documented silent-no-op
  behaviour. The warning now fires only when the alias actually changes
  rtol.

Existing alias-resolution behaviour (alias-only copy with warning,
distinct-value conflict raising ValueError, equal-value silence) is
unchanged.

The structure-table cache check looked for solidus.dat and liquidus.dat,
but the table writer emits solidus_P-S.dat and liquidus_P-S.dat, so the
check never matched and the full pressure-entropy table set regenerated
on every initialisation and every grid point. Point the cache check at
the file names the writer actually produces.

The module-level density seed cache was unkeyed, so a second planet
solved in the same process could start its Picard iteration from another
planet's density profile. Tag the cache with the planet's total mass and
core and mantle fractions, and reuse the seed only when it matches. The
seed only accelerates convergence; it never changes the converged
structure.

Correct two comments that described the first-call core-mantle-boundary
pressure fallback as a fixed 135 GPa value. It actually uses the
mass-aware Noack and Lasbleis (2020) estimate.

Interior radius solve:
- The secant radius solver now hard-fails when scipy reports a
  non-converged, non-finite, or non-positive root instead of writing a
  garbage radius into the core-mass calculation and the rest of the
  trajectory, mirroring the Zalmoxis mass-anchor check.
- calculate_core_mass cubes the core fraction as a radius fraction, so it
  now checks that core_frac_mode is 'radius'. The config validator already
  guarantees this for the only path that reaches it; the check makes the
  dependency explicit and loud if the validator is ever relaxed.

Aragog energetics:
- In grey_body surface mode the F_int column reports the surface
  heat-flux node Aragog actually integrated rather than the atmosphere
  flux F_atm, so the interior/atmosphere parity comparison is meaningful.
  Flux mode is unchanged, where the two are equal by construction.
- The retry-ladder exhaustion error distinguishes a CVODE failure from a
  result rejected for an over-threshold core-temperature jump instead of
  always reporting status=0.
- Remove an unreachable core_bc fallback that would have silently swapped
  in a different core model.

Other:
- The cumulative energy residual anchors on the first populated enthalpy
  row, so a zero placeholder cannot fold the absolute mantle enthalpy
  into the residual.
- The escape-timescale estimate guards its surface-pressure division, so
  a fully escaped atmosphere yields an infinite timescale instead of a
  NaN that would poison the timestep selector.
- The research-only JAX interior path reports radiogenic and tidal
  heating as separate surface fluxes instead of folding both into the
  radiogenic column.

Tests set core_frac_mode and drive the radius solver through a converged
root.

Binodal hydrogen partitioning:
- The element-level H_kg_atm and H_kg_liquid totals now follow the H2 the
  binodal moves between atmosphere and melt. H2 is pure hydrogen by mass,
  so the hydrogen shifted equals the H2 shifted. Without this the
  atmospheric element-ratio columns kept counting the relocated hydrogen.

Dummy outgassing:
- A user-supplied oxygen budget is preserved instead of being overwritten
  by the small stoichiometric outgassed O. This keeps dummy O accounting
  consistent with the other elements and stops the IC oxygen check from
  spuriously failing an otherwise valid dummy run.

IC oxygen consistency check:
- The check fires once at the initial condition as documented. The user
  O budget is no longer re-stashed as the check baseline on every
  initialisation iteration, which previously re-armed the check each time.

Escape:
- The bulk-escape fallback that zeros every per-element escape rate now
  logs a warning, because it leaves the total escape rate nonzero, so the
  per-element sum no longer matches the total.

Also clarify the comment on the atmosphere mass-conservation invariant to
describe what it guards.

AGNI atmosphere:
- Guard the top-of-atmosphere albedo against zero instellation (nightside
  or no stellar flux), where the upward/downward shortwave ratio is
  undefined.
- The opaque surface-pressure update now sets the bottom-of-atmosphere
  pressure from the new surface pressure. It was assigning the field to
  itself, so a changed surface pressure was not carried into the grid.

Config:
- A supplied planet.R_int_override must be a positive radius in metres.

Coupling loop:
- The solvus-frame boundary overrides for the atmosphere step are restored
  in a finally block, so a raising atmosphere step cannot leave the
  helpfile row in the solvus frame for the rest of the iteration.

Environment diagnostics:
- proteus doctor distinguishes an undeterminable git status from a clean
  tree for an editable install whose source is not a git repository,
  instead of silently reporting it clean.

Dummy atmospheric chemistry:
- Clarify that the per-level renormalisation rescales the cold-trap and
  photolysis adjustments, so they are qualitative shape hints in this
  parameterised model rather than conserved physics.

Interior structure:
- The R_int_override path now refreshes the volatile inventory and total
  planet mass, matching the root-finder and the dummy and Zalmoxis
  structure paths, so it no longer leaves M_ele and M_planet stale after
  the override solve.

CLI:
- The --deterministic re-exec now works under 'python -m proteus.cli',
  where it is re-launched via -m, in addition to the 'proteus' console
  script. The module path in argv[0] is not directly executable, so the
  previous re-exec form failed for the -m launch.

Environment diagnostics:
- The editable-install annotation cross-checks the package actually on the
  import path. When a pinned install shadows an editable sibling, doctor
  reports the location it imports from instead of silently trusting the
  editable checkout metadata. The lookup uses find_spec, so it does not
  import the package.

Module setup scripts:
- get_aragog.sh and get_zalmoxis.sh check out the version floor declared
  in pyproject.toml after cloning, so editable installs are reproducible
  across machines and CI instead of tracking the default branch. To
  develop against the latest, run 'git checkout main' in the checkout and
  reinstall.

Inference robustness:
- Inference child PROTEUS runs now honour a configurable timeout (the
  optional inference config field child_timeout_s, default 6 hours), so a
  single wedged simulation cannot hang the whole batch with no diagnostic.
  The per-child timeout bounds each subprocess; the initial-sampling pool
  also bounds the whole batch. A value of 0 disables it.

Data path:
- The FWL_DATA directory is resolved through one shared helper, so the CLI
  and the data loader agree on the repo-local default when FWL_DATA is
  unset, instead of the loader falling back to a platform user-data
  directory that the runtime would not look in.

Config validation:
- planet.fO2_source rejects the reserved "from_mantle_redox" value at the
  field level (on a bare Planet and on assignment), not only when a full
  Config is built, so it cannot reach the outgas dispatch with a vague
  error.
- outgas.fO2_shift_IW is bounded to [-12, +12], so an out-of-range value
  fails at config load instead of crashing inside the chemistry solver.
- The from_O_budget warning states that fO2_shift_IW is used as the
  solver's initial guess, rather than "ignored at runtime" (it seeds the
  solve).

Chemistry coupling (from_O_budget):
- Pass a fixed seed to the authoritative-O solver so the derived initial
  redox state is reproducible run to run and pinnable by --deterministic.
- Flip the atmodeller O_res sign to (atmosphere + dissolved) - target so
  it matches the CALLIOPE convention in the shared helpfile column.
- The atmodeller early returns (no volatiles, or T below the floor) mark
  fO2_shift_IW_derived and O_res undefined under from_O_budget rather than
  leaving the user pre-seed, which would read as "equilibrated".
- Reading O_kg_total under from_O_budget raises a clear error if the
  column is absent, for example on a resume from an older helpfile.

Accounting and docs:
- Correct the assert_mass_conservation and M_vol_initial descriptions to
  current-state whole-element (oxygen-inclusive) wording.
- Fix the dt.minimum floor comment, which applies to all dynamic-stepping
  methods, not only the adaptive branch.
- Add a worked from_O_budget block to input/all_options.toml.

Tests updated for the validation and atmodeller changes above. The
from_O_budget round-trip at reducing fO2 is no longer flaky now that the
solver is seeded.

The git-head, git-dirty, and editable-checkout-path helpers had tests
whose only assertion was "result is None", which passes even if the
helper short-circuits without doing its work. Each now adds a second
assertion: the git helpers contrast a non-repo (None) against an
initialised repo (a 40-char hash, or False for a clean tree), and the
editable-checkout tests confirm the metadata lookup and direct_url.json
read were attempted before None is returned.

Lower the test-quality baseline to match.

The test asserts C mass > H mass under an elevated carbon budget, but
the base config (dummy.toml) pins C_mode = 'ppmw', so C_budget = 2.0 was
2 ppmw of carbon against a much larger hydrogen budget and the assertion
could not hold. Set C_mode = 'C/H' in the test so C_budget = 2.0 means a
C/H mass ratio of 2, matching the scenario the test describes, regardless
of the base config's element modes.

The dummy interior does not advance model time, so the maximum-time stop
condition never fires and the coupled loop ran toward its 9000-iteration
safety ceiling, calling the JANUS radiative-transfer solver thousands of
times. The test previously completed only because the dummy outgas
produced an empty atmosphere, which made each JANUS solve trivial; now
that the dummy outgas yields a real atmosphere, each solve does real work.

Cap the loop iteration count to the init loops plus one step, set a thin
volatile budget so the radiative-transfer step is cheap, and raise the
per-test timeout to match a real multi-solve JANUS run. The test now
verifies JANUS initialisation and a single coupled step in bounded time.

The slow-tier test that runs real Zalmoxis + Aragog + CALLIOPE borrowed
input/dummy.toml as its base config. That file is tuned for the all-dummy
tutorial and CI wiring runs, and its volatile budgets and cooling were
recently adjusted. Under the new budgets the coupled trajectory moves
T_magma and the dissolved-volatile fractions far enough within the short
run to cross the dynamic structure-refresh thresholds. Each crossing
re-solves the full mass-radius structure (about ten minutes) and returns
a slightly different radius. That broke the test two ways: the per-row
radius is no longer constant, so the bit-stable R_int check failed on
the fast runner, and the repeated re-solves blew the wall-clock budget
on the slow runner.

Move the test onto a dedicated config it owns
(tests/integration/zalmoxis_aragog_calliope.toml) with structure refresh
disabled (update_interval = 0). Zalmoxis now solves the structure once at
the initial condition and the radius is held fixed for the rest of the
run, so the constant-R_int invariant holds by construction and the run
stays within its time budget. The config is independent of dummy.toml, so
future tutorial retuning of that file no longer perturbs this test. The
three physics slots under test still run their production backends and
the init equilibration loop still runs; only the per-iteration refresh is
turned off.